home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 49 / Amiga Format CD49 (2000-01-17)(Future Publishing)(GB)(Track 1 of 3)[!][issue 2000-02].iso / -serious- / programming / mui / mcc_tipofday / developer / autodocs / mcc_tipwindow.doc
Text File  |  1999-11-30  |  7KB  |  179 lines
  1. TABLE OF CONTENTS
  2.  
  3. Tipwindow.mcc/Tipwindow.mcc
  4. Tipwindow.mcc/Technical notes
  5. Tipwindow.mcc/MUIA_Tip_FileBase
  6. Tipwindow.mcc/MUIM_Tip_GoHomePage
  7. Tipwindow.mcc/MUIM_Tip_Show
  8.  
  9. Tipwindow.mcc/Tipwindow.mcc
  10.  
  11.   Many programs on other operating systems often offer so called
  12.   "Tip of the day" stickers. It's mostly small window opened on
  13.   program startup, showing valuable (more or less) information about
  14.   the program, some useful information, keyboard shortcuts or just
  15.   neat tips or quick how-to solutions...
  16.  
  17.   I think, that from the user's point of view it's good idea to have
  18.   such feature, especially Tips can be turned off if you felt bored.
  19.   As you probably guessed, this class is supposed to handle such
  20.   tips for your MUI based application. See the enclosed demonstration
  21.   for more details.
  22.  
  23.   You like the class? Feel free to use it in your programs.
  24.  
  25.   Tip Of The Day class is freeware software, but it's copyrighted
  26.   © 1999 by Marcin Orlowski <carlos@amiga.com.pl>
  27.  
  28.  
  29.   $Id: MCC_Tipwindow.doc,v 1.6 1999/11/24 22:06:24 carlos Exp $
  30.  
  31. Tipwindow.mcc/Technical notes
  32.  
  33.   Tips are stored in IFF file. The structure of the file is
  34.   rather simple:
  35.  
  36.     chunk  'MAX ' holds total number of tips present in the file
  37.     chunks '0000' till 'ffff' (note case IS important!) holds
  38.            all the tip texts.
  39.  
  40.   Tips converter takes plain ASCII file as input and writes each
  41.   line as separate tip. To support multiline tips, converter handles
  42.   all these backslashed (e.g. "\n") characters, and converts them
  43.   properly. It also handles hex/dec/oct/bin numbers (e.g. \033), so
  44.   you can use all MUI text formatting sequences like \033b to have
  45.   text boldfaced, \033u to have it underlined etc.
  46.  
  47.   Since release 15.1, Tipboard supports localized tips. According to
  48.   your system settings, the following locations will be checked against
  49.   valid tips database
  50.  
  51.       PROGDIR:Tips/$language/filebase.tips
  52.       PROGDIR:Catalogs/$language/filebase.tips
  53.       LOCALE:Catalogs/$language/filebase.tips
  54.       LOCALE:Tips/$language/filebase.tips
  55.       LOCALE:$language_filebase.tips
  56.       PROGDIR:Tips/$language_filebase.tips
  57.       PROGDIR:Tips/english/filebase.tips
  58.       PROGDIR:Tips/filebase.tips
  59.       PROGDIR:filebase.tips
  60.  
  61.   where $language is your current system language (e.g. "english",
  62.   "polski", "deutsch" etc). File base meaning is described in the
  63.   MUIA_Tip_FileBase chapter.
  64.  
  65.   Class private data (".tipc" file) is always stored in 
  66.   PROGDIR:filebase.tipc file
  67.  
  68.   To allow user snapshot the TipOfTheDay window (size/position etc),
  69.   the window uses own window ID = 'TODD'. I don't expect it would
  70.   ever collide with your application window ID's, but in case
  71.   I am wrong, you can always set your own ID at object creation
  72.   time to override default one (Tipwindow.mcc is a subclass of
  73.   the window class)
  74.  
  75. Tipwindow.mcc/MUIA_Tip_FileBase
  76.  
  77.     NAME
  78.         MUIA_Tip_FileBase -- [ISG], char *   v15
  79.  
  80.     FUNCTION
  81.         Specifies custom file base (root name) for all Tip related
  82.         files this class uses. The file base it copied into
  83.         internal buffer (which can hold up to 256 characters).
  84.  
  85.     NOTE:
  86.         If you don't specify your own file base, Tip class will
  87.         try to find out it by itself, by quering your Applicaiton
  88.         object for MUIA_Application_Base, and if fail, for
  89.         MUIA_Application_Title. To avoid problems on multiple instances 
  90.         of your program, the class will strip any dot suffix of your
  91.         application base found in range of 4 characters starting
  92.         from the end of the name (e.g. "MyApp.3" will result in
  93.         "MyApp", but "My.Program" will result in "My.Program").
  94.         Unfortunately, MUIA_Application_SingleTask is not gettable
  95.         recently, so better don't use dotted base names (e.g. base
  96.         name like "My.App" will cause problems as it will be taken
  97.         as "My" filebase).
  98.  
  99.         If you need custom value, it appears wise to specify this
  100.         attribute on object creation time, and to keep it untouched
  101.         later on.
  102.  
  103.     FILES
  104.         Tips of the day are stored in the database which name
  105.         is built based on the FileBase attribute and the
  106.         ".tips" suffix. Class settings ("show tips on startup")
  107.         and other data are kept in ".tipc" file in your app's home
  108.         directory. The ".tipc" file is created when the class is going
  109.         to be disposed (OM_DISPOSE), to avoid unnecessary I/O accesses.
  110.         But when the state of "show tips on startup" checkmark change
  111.         (e.g. due to user's action) the ".tipc" file is written
  112.         immidiately.
  113.  
  114.         
  115.     EXAMPLE
  116.         set(obj, MUIA_Tip_FileBase, "myapp");
  117.  
  118.         the class will be then looking for "myapp.tips" database,
  119.         and will keep own data in "myapp.tipc" file.
  120.  
  121.     SEE ALSO
  122.         See example demo program about class usage
  123.  
  124. Tipwindow.mcc/MUIM_Tip_GoHomePage
  125.  
  126.     NAME
  127.         MUIM_Tip_GoHomePage          v15
  128.  
  129.     FUNCTION
  130.         If there's OpenURL.library installed and properly
  131.         configured, this method should order your favourite
  132.         browser to visit TipOfTheDay class' homepage. This method
  133.         is called when user click on the bulb image (this is
  134.         hidden feature ;-)
  135.         
  136.     EXAMPLE
  137.         DoMethod(obj, MUIM_Tip_GoHomePage );
  138.  
  139.     SEE ALSO
  140.  
  141. Tipwindow.mcc/MUIA_Tip_Show
  142.  
  143.     NAME
  144.         MUIM_Tip_Show      v15
  145.  
  146.         DoMethod(obj, MUIM_Tip_Show, Flags );
  147.  
  148.  
  149.     FUNCTION
  150.         Shows Tip of the day. If called sequently, will show
  151.         next tip each time. Tips never ends (when showing forward,
  152.         1st one will be shown after last, or vice versa when showing
  153.         tips backwards)
  154.  
  155.     FLAGS
  156.         MUIV_Tip_Show_Startup
  157.         MUIV_Tip_Show_Next
  158.         MUIV_Tip_Show_Prev
  159.         MUIV_Tip_Show_Random
  160.  
  161.     NOTE: When MUIV_Tip_Show_Next, Prev or Random are used,
  162.           the Tip window will pop up, no matter what the state of
  163.           "show tip on startup" is.  MUIV_Tip_Show_Startup is
  164.           almost the same as MUIV_Tip_Show_Next, but it takes
  165.           care of user will (stored in ".tipc" file). It's
  166.           recommended to use this flag when you show tips on
  167.           startup, but also to have menu item (like "Show tip of
  168.           the day...") that will call this method with
  169.           MUIV_Tip_Show_Next, to allow user to change his mind
  170.           (or to read more tips w/o forcing him to restart your
  171.           application which should be totally lame ;-)
  172.  
  173.     EXAMPLE
  174.         DoMethod( obj, MUIA_Tip_Show, MUIV_Tip_Show_Startup );
  175.  
  176.     SEE ALSO
  177.         See example demo program about class usage
  178.  
  179.